<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
	<title>SQLAlchemy 0.4 Documentation - module sqlalchemy.ext.associationproxy</title>
	
    
    <link rel="stylesheet" href="style.css"></link>
    <link rel="stylesheet" href="docs.css"></link>
    <link href="syntaxhighlight.css" rel="stylesheet" type="text/css"></link>
    <script src="scripts.js"></script>

    <link rel="stylesheet" href="docutil.css"></link>



</head>
<body>








<div id="topanchor"><a name="top">&nbsp;</a></div>


<h1>SQLAlchemy 0.4 Documentation</h1>

<div id="pagecontrol"><a href="index.html">Multiple Pages</a> | <a href="documentation.html">One Page</a></div>

<div class="versionheader">Version: 0.4.8   Last Updated: 10/12/08 13:33:19</div>












    <div class="topnav">

    
    <div class="navbanner">
        <a href="index.html" class="totoc">Table of Contents</a>
        
    <div class="prevnext">
            Up: <a href="docstrings.html">API Documentation</a>

               |   
            Previous: <a href="sqlalchemy_ext_declarative.html">module sqlalchemy.ext.declarative</a>

               |   
            Next: <a href="sqlalchemy_ext_orderinglist.html">module sqlalchemy.ext.orderinglist</a>
    </div>

        <h2>module sqlalchemy.ext.associationproxy</h2>
    </div>

	
	
    <ul>
        
        <li><a style="" href="sqlalchemy_ext_associationproxy.html#docstrings_sqlalchemy.ext.associationproxy_modfunc">Module Functions</a></li>

	        <li>
                
    <ul>
        
        <li><a style="" href="sqlalchemy_ext_associationproxy.html#docstrings_sqlalchemy.ext.associationproxy_modfunc_association_proxy">association_proxy()</a></li>

    </ul>

	        </li>
        
        <li><a style="" href="sqlalchemy_ext_associationproxy.html#docstrings_sqlalchemy.ext.associationproxy_AssociationProxy">class AssociationProxy(object)</a></li>

    </ul>

	</div>



    

    
    
    <A name="docstrings_sqlalchemy.ext.associationproxy"></a>
    
    <div class="sectionL2">

    <h3>module sqlalchemy.ext.associationproxy</h3>
    
    
    <div class="darkcell"><p>Contain the <tt class="docutils literal"><span class="pre">AssociationProxy</span></tt> class.</p>
<p>The <tt class="docutils literal"><span class="pre">AssociationProxy</span></tt> is a Python property object which provides
transparent proxied access to the endpoint of an association object.</p>
<p>See the example <tt class="docutils literal"><span class="pre">examples/association/proxied_association.py</span></tt>.</p>
</div>
    

        
    
    <A name="docstrings_sqlalchemy.ext.associationproxy_modfunc"></a>
    
    <div class="sectionL3">

    <h3>Module Functions</h3>
    
    
                
    <div class="darkcell">
    
    <A name="docstrings_sqlalchemy.ext.associationproxy_modfunc_association_proxy"></a>
    <b>def association_proxy(<i>targetcollection</i>, <i>attr</i>, <i>**kw</i>)</b>
    <div class="docstring">
    <p>Convenience function for use in mapped classes.  Implements a Python
property representing a relation as a collection of simpler values.  The
proxied property will mimic the collection type of the target (list, dict
or set), or in the case of a one to one relation, a simple scalar value.</p>
<dl class="docutils">
<dt>targetcollection</dt>
<dd>Name of the relation attribute we'll proxy to, usually created with
'relation()' in a mapper setup.</dd>
<dt>attr</dt>
<dd><p class="first">Attribute on the associated instances we'll proxy for.  For example,
given a target collection of [obj1, obj2], a list created by this proxy
property would look like
[getattr(obj1, attr), getattr(obj2, attr)]</p>
<p class="last">If the relation is one-to-one or otherwise uselist=False, then simply:
getattr(obj, attr)</p>
</dd>
<dt>creator (optional)</dt>
<dd><p class="first">When new items are added to this proxied collection, new instances of
the class collected by the target collection will be created.  For
list and set collections, the target class constructor will be called
with the 'value' for the new instance.  For dict types, two arguments
are passed: key and value.</p>
<p>If you want to construct instances differently, supply a 'creator'
function that takes arguments as above and returns instances.</p>
<p>For scalar relations, creator() will be called if the target is None.
If the target is present, set operations are proxied to setattr() on the
associated object.</p>
<p class="last">If you have an associated object with multiple attributes, you may set up
multiple association proxies mapping to different attributes.  See the
unit tests for examples, and for examples of how creator() functions can
be used to construct the scalar relation on-demand in this situation.</p>
</dd>
</dl>
<p>Passes along any other arguments to AssociationProxy</p>

    </div>
    </div>

        

    </div>




            
    

    
    
    <A name="docstrings_sqlalchemy.ext.associationproxy_AssociationProxy"></a>
    
    <div class="sectionL3">

    <h3>class AssociationProxy(object)</h3>
    
    
    <div class="darkcell"><p>A property object that automatically sets up <cite>AssociationLists</cite>
on an object.</p>
</div>
    

                    
    <div class="darkcell">
    
    <A name=""></a>
    <b>def __init__(<i>self</i>, <i>targetcollection</i>, <i>attr</i>, <i>creator=None</i>, <i>getset_factory=None</i>, <i>proxy_factory=None</i>, <i>proxy_bulk_set=None</i>)</b>
    <div class="docstring">
    <p>Arguments are:</p>
<dl class="docutils">
<dt>targetcollection</dt>
<dd>Name of the collection we'll proxy to, usually created with
'relation()' in a mapper setup.</dd>
<dt>attr</dt>
<dd>Attribute on the collected instances we'll proxy for.  For example,
given a target collection of [obj1, obj2],
a list created by this proxy property would look like
[getattr(obj1, attr), getattr(obj2, attr)]</dd>
<dt>creator</dt>
<dd><p class="first">Optional. When new items are added to this proxied collection, new
instances of the class collected by the target collection will be
created.  For list and set collections, the target class
constructor will be called with the 'value' for the new instance.
For dict types, two arguments are passed: key and value.</p>
<p class="last">If you want to construct instances differently, supply a 'creator'
function that takes arguments as above and returns instances.</p>
</dd>
<dt>getset_factory</dt>
<dd><p class="first">Optional.  Proxied attribute access is automatically handled
by routines that get and set values based on the <cite>attr</cite> argument
for this proxy.</p>
<p class="last">If you would like to customize this behavior, you may supply a
<cite>getset_factory</cite> callable that produces a tuple of <cite>getter</cite> and
<cite>setter</cite> functions.  The factory is called with two arguments,
the abstract type of the underlying collection and this proxy
instance.</p>
</dd>
<dt>proxy_factory</dt>
<dd>Optional.  The type of collection to emulate is determined by
sniffing the target collection.  If your collection type can't be
determined by duck typing or you'd like to use a different collection
implementation, you may supply a factory function to produce those
collections.  Only applicable to non-scalar relations.</dd>
<dt>proxy_bulk_set</dt>
<dd>Optional, use with proxy_factory.  See the _set() method for
details.</dd>
</dl>

    </div>
    </div>

                    
         <div class="darkcell">
         <A name=""></a>
         <b>target_class = property()</b>
         <div class="docstring">
         
         </div> 
         </div>

                    
    <div class="darkcell">
    
    <A name=""></a>
    <b>def __delete__(<i>self</i>, <i>obj</i>)</b>
    <div class="docstring">
    
    </div>
    </div>

                    
    <div class="darkcell">
    
    <A name=""></a>
    <b>def __get__(<i>self</i>, <i>obj</i>, <i>class_</i>)</b>
    <div class="docstring">
    
    </div>
    </div>

                    
    <div class="darkcell">
    
    <A name=""></a>
    <b>def __set__(<i>self</i>, <i>obj</i>, <i>values</i>)</b>
    <div class="docstring">
    
    </div>
    </div>


    

            <a href="#top" class="totoc">back to section top</a>
    </div>



    

    </div>





    <div class="bottomnav">
        
    <div class="prevnext">
            Up: <a href="docstrings.html">API Documentation</a>

               |   
            Previous: <a href="sqlalchemy_ext_declarative.html">module sqlalchemy.ext.declarative</a>

               |   
            Next: <a href="sqlalchemy_ext_orderinglist.html">module sqlalchemy.ext.orderinglist</a>
    </div>

    </div>








</body>
</html>






